<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
	<TITLE></TITLE>
	<META NAME="GENERATOR" CONTENT="OpenOffice.org 2.0  (Linux)">
	<META NAME="CREATED" CONTENT="20061209;9275900">
	<META NAME="CHANGED" CONTENT="20061209;11592700">
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<H1 ALIGN=CENTER>The Spring Python PetClinic Application</H1>
<P><FONT SIZE=4><B>Updated : <BR></B>
&nbsp;&nbsp;&nbsp; 23-OCT-2008 - Greg Turnquist, updated with new terminology<BR>
&nbsp;&nbsp;&nbsp; 30-APR-2008 - Greg Turnquist, updated for new site<BR>
&nbsp;&nbsp;&nbsp; 09-DEC-2006 - Greg Turnquist, adapted for Spring Python<BR>
&nbsp;&nbsp;&nbsp; 01-DEC-2004 - Ken Krebs<BR>
&nbsp;&nbsp;&nbsp; 16-AUG-2003 - Ken Krebs</FONT></P>
<H2>Introduction</H2>
<P><A HREF="https://springpython.webfactional.com">Spring Python</A> is a collection of small, well-focused, loosely
coupled <A HREF="http://www.python.org/">Python</A> frameworks that
can be used independently or collectively to build industrial
strength applications of many different types. The PetClinic sample
application is designed to show how the Spring Python application
frameworks can be used to build simple, but powerful
database-oriented applications. It will demonstrate the use of Spring
Python's core functionality:</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in">Object-based application
	configuration using Inversion-Of-Control (In java, these are called
	JavaBeans)</P>
	<LI><P STYLE="margin-bottom: 0in">Model-View-Controller web
	Presentation Layer 
	</P>
	<LI><P STYLE="margin-bottom: 0in">Practical database access through
	MySQL 
	</P>
</UL>
<P>The Spring Python frameworks provide a great deal of useful
infrastructure to simplify the tasks faced by application developers.
This infrastructure helps developers to create applications that are
:</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><B><U>concise</U></B> by handling
	a lot of the complex control flow that is needed to use certain
	Python API's, such as <A HREF="http://www.python.org/dev/peps/pep-0249">DB-2
	API</A>, remoting through <A HREF="http://pyro.sourceforge.net/">PYRO</A>
		</P>
	<LI><P STYLE="margin-bottom: 0in"><B><U>flexible</U></B> by
	simplifying the process of external application configuration
	through the use of <A HREF="http://diveintopython.org/power_of_introspection/index.html">Introspection</A>
	and object creation. This allows the developer to achieve a clean
	separation of configuration data from application code. All
	application objects, including database connection factories,
	templates, and proxies are objects that can be configured
	externally. 
	</P>
	<LI><P><B><U>maintainable</U></B> by facilitating a clean separation
	of the application layers. It most importantly helps maintain the
	independence of the Business Layer from the Presentation layer.
	PetClinic demonstrates the use of a Model-View-Controller based web
	presentation framework that can work seamlessly with many different
	types of view technologies. The Petclinic web application
	demonstrates &quot;plugging in&quot; to one popular Python web
	framework, <A HREF="http://www.cherrypy.org/">CherryPy</A>, while
	keeping the database layer and the model definitions neatly
	separated. This helps developers to implement their Presentation as
	a clean and thin layer focused on its main missions of translating
	user actions into application events and rendering model data. 
	</P>
</UL>
<P>It is assumed that users of this tutorial will have a basic
knowledge of object-oriented design, Python, and relational
databases.<BR><BR>Since the purpose of the sample application is
tutorial in nature, the implementation presented here will of course
provide only a small subset of the functionality that would be needed
by a real world version of a PetClinic application.</P>
<H2>PetClinic Sample Application Requirements</H2>
<P>The application requirement is for an information system that is
accessible through a web browser. The users of the application are
employees of the clinic who in the course of their work need to view
and manage information regarding the veterinarians, the clients, and
their pets. The sample application supports the following:<BR><BR><B>Use
Cases:</B></P>
<UL>
	<LI><P STYLE="margin-bottom: 0in">View a list of veterinarians and
	their specialties 
	</P>
	<LI><P STYLE="margin-bottom: 0in">View information pertaining to a
	pet owner 
	</P>
	<LI><P STYLE="margin-bottom: 0in">Update the information pertaining
	to a pet owner 
	</P>
	<LI><P STYLE="margin-bottom: 0in">Add a new pet owner to the system 
	</P>
	<LI><P STYLE="margin-bottom: 0in">View information pertaining to a
	pet 
	</P>
	<LI><P STYLE="margin-bottom: 0in">Update the information pertaining
	to a pet 
	</P>
	<LI><P STYLE="margin-bottom: 0in">Add a new pet to the system 
	</P>
	<LI><P STYLE="margin-bottom: 0in">View information pertaining to a
	pet's visitation history 
	</P>
	<LI><P>Add information pertaining to a visit to the pet's visitation
	history 
	</P>
</UL>
<P><B>Business Rules:</B></P>
<OL>
	<LI><P>An owner may not have multiple pets with the same
	case-insensitive name. 
	</P>
</OL>
<H2>PetClinic Sample Application Design &amp; Implementation</H2>
<P><B><U>Server Technology</U></B><BR>The sample application is
written using <A HREF="http://www.cherrypy.org/">CherryPy</A> as the
web container. CherryPy applications are self-contained web servers
utilizing Python's built in HTTPServer objects. CherryPy
applications do not require a 3rd party web server, such as Apache or
IIS. However, it is possible to <A HREF="http://cherrypy.org/wiki/BehindApache">configure
the CherryPy web application</A> to be fronted by a web server, and
even spawned.<BR>In order to run the application, you must install
CherryPy. You can download the package from their web site and
install it through the traditional Python mechanism.</P>
<P>If you are running Ubuntu/Linux, type: <CODE><FONT FACE="Courier New, monospace">sudo
apt-get install python-cherrypy</FONT></CODE></P>
<P> <BR><B><U>Database Technology</U></B><BR>The sample application
uses a relational database for data storage. To reset the database,
it is probably easiest to just re-run the setup.py script.</P>
<UL>
	<LI><P>Support is provided for <A HREF="http://mysql.com/">MySQL</A>.
	Setup requires the user to provide the MySQL &quot;root&quot;
	password, in order to setup to the &quot;springpython&quot; user and
	&quot;petclinic&quot; database. You need to have MySQL python module
	installed.</P>
	<UL>
		<UL>
			<LI><P>If you are running Ubuntu/Linux, type: <CODE><FONT FACE="Courier New, monospace">sudo
			apt-get install python-mysqldb</FONT></CODE> 
			</P>
		</UL>
	</UL>
</UL>
<P STYLE="margin-bottom: 0in"><BR><B><U>Development Environment</U></B><BR>You
need to either have Spring Python installed on your machine, which
will put the libraries in your Python path, or you can download the
software and manually configure your PYTHONPATH to see the folder
containing &quot;springpython&quot;.</P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<TABLE BORDER=1 CELLPADDING=2 CELLSPACING=2>
	<TR>
		<TD>
			<P>python</P>
		</TD>
		<TD>
			<P>2.4.3-11ubuntu3</P>
		</TD>
	</TR>
	<TR>
		<TD>
			<P>python-mysqldb</P>
		</TD>
		<TD>
			<P>1.2.1c3-4ubuntu4</P>
		</TD>
	</TR>
	<TR>
		<TD>
			<P>python-cherrypy</P>
		</TD>
		<TD>
			<P>2.2.1-3</P>
		</TD>
	</TR>
</TABLE>
<P><BR><BR>
</P>
<P><B>NOTE:</B> The version numbers listed are those that were used
in the development of the PetClinic application. Other versions of
the same tools may or may not work.<BR><BR>Download links for the
various tools needed are provided in the Developer Instructions
section.<BR><BR><B><U>PetClinic Database</U></B><BR>The following is
an overview of the database schema used in PetClinic. Detailed field
descriptions can be found in the <B><I>&quot;initDB.txt&quot;</I></B>
SQL script files in the database-specific &quot;db&quot;
sub-directories. All &quot;id&quot; key fields are of type
<B><I>int</I></B>.<BR><BR>TABLE: <B><I>owners</I></B><BR>&nbsp;&nbsp;&nbsp;
PRIMARY KEY <B>id<BR><BR></B>TABLE: <B><I>types</I></B><BR>&nbsp;&nbsp;&nbsp;
PRIMARY KEY <B>id</B><BR><BR>TABLE: <B><I>pets</I></B><BR>&nbsp;&nbsp;&nbsp;
PRIMARY KEY <B>id</B><BR>&nbsp;&nbsp;&nbsp; FOREIGN KEY <B>type_id</B>
references the <B><I>types</I></B> table <B>id </B>field<BR>&nbsp;&nbsp;&nbsp;
FOREIGN KEY <B>owner_id</B> references the <B><I>owners</I></B> table
<B>id </B>field<BR><BR>TABLE: <B><I>vets</I></B><BR>&nbsp;&nbsp;&nbsp;
PRIMARY KEY <B>id</B><BR><BR>TABLE: <B><I>specialties</I></B><BR>&nbsp;&nbsp;&nbsp;
PRIMARY KEY <B>id</B><BR><BR>TABLE: <B><I>vet_specialties</I></B>- a
link table for <B><I>vets</I></B> and their <B><I>specialties</I></B><BR>&nbsp;&nbsp;&nbsp;
FOREIGN KEY <B>vet_id</B> references the <B><I>vets</I></B> table <B>id</B>
field<BR>&nbsp;&nbsp;&nbsp; FOREIGN KEY <B>specialty_id</B>
references the <B><I>specialties</I></B> table <B>id </B>field<BR><BR>TABLE:
<B><I>visits</I></B><BR>&nbsp;&nbsp;&nbsp; PRIMARY KEY <B>id</B><BR>&nbsp;&nbsp;&nbsp;
FOREIGN KEY <B>pet_id</B> references the <B><I>pets </I></B>table <B>id
</B>field<BR><BR><B><BR><U>Directory Structure</U></B></P>
<UL>
	<LI><P STYLE="font-weight: medium; text-decoration: none">petclinic
	– contains the setup.py script in order to configure things (NOT
	install the application)</P>
	<UL>
		<UL>
			<LI><P STYLE="font-weight: medium; text-decoration: none">cherrypy</P>
			<UL>
				<LI><P STYLE="font-weight: medium; text-decoration: none">html –
				static content, including this page</P>
				<LI><P STYLE="font-weight: medium; text-decoration: none">images
				– static content</P>
			</UL>
			<LI><P STYLE="font-weight: medium; text-decoration: none">db –
			contains DBMS-neutral scripts to populate the database used for
			the PetClinic application</P>
			<UL>
				<LI><P STYLE="font-weight: medium; text-decoration: none">mysql –
				MySQL scripts to initialize the database</P>
			</UL>
		</UL>
	</UL>
</UL>
<H2>PetClinic Application Design</H2>
<H3><U><B>Controller Layer</B></U></H3>
<P>The Controller Layer consists of the APIs used to contain the
business logic needed by the View layer. For the PetClinic sample
application, this is principally database calls. These objects are
defined in the <B>controller.py</B> module.</P>
<P>Since the Spring Python PetClinic application is all about
database access and there is very little business logic in the
application outside of that, there is no separation of the primary
Business and Persistence Layer API's. While this design technique
should not be used for an application with more complex business
logic, it is acceptable here because all of the non-persistence
related business rules have been implemented in business objects and
have not leaked into the Persistence Layer. The most important facet
of the design is that the Business and Persistence Layers are
<B>COMPLETELY </B>independent of the Presentation Layer.<BR><BR>The
Persistence Layer currently <B>only</B> supports MySQL.</P>
<H3 STYLE="font-style: normal"><U>Model Layer</U></H3>
<P STYLE="font-style: normal; text-decoration: none">The <B>Model
Layer</B> defines the entities returned from the database by the
Controller layer. These objects are defined in the <B>model.py</B>
module.</P>
<H3><U>Presentation Layer</U></H3>
<P>The <B>Presentation Layer</B>, or View is run on the CherryPy web
application framework. The objects are defined in the <B>view.py</B>
module. It contains several functions which are mapped to URLs by the
framework. For each page, there is a defined function. Each of the
functions is responsible for returning HTML content. To keep
presentation information decoupled from controller logic, the 
</P>
<H3><U>Launcher</U></H3>
<P>A fourth module is the <B>petclinic.py</B> bootstrapping script.
It is responsible for loading the Application Context, which wires
all the objects together. It also launches the CherryPy web
server, making it ready to serve content.</P>
<P>A Spring Python <B><FONT SIZE=3>springpython.context<I>.</I>ApplicationContext</FONT>
</B>object provides a map of user-defined objects. These
objects constitute the <B>View</B> and <B>Controller </B><SPAN STYLE="font-weight: medium">layers</SPAN>
of PetClinic. The following objects are defined in the PetClinic
<I>applicationContext.xml</I> file:</P>
<OL>
	<LI><P STYLE="margin-bottom: 0in"><B><I>connectionFactory </I></B>is
	a object that holds the connection information and the call to
	connect to the database. It is DBMS specific. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B><I>controller </I></B>is a
	object that defines the implementation of the <B>Clinic </B>interface
	that provides the primary Business Layer API of the application. 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><B><I>view </I></B>is a object
	that defines all the CherryPy exposed functions that end up getting
	mapped to URLs.</P>
</OL>
<P><BR><BR>
</P>
<P>The Application Context file makes it very easy to decouple the
controller layer from being DDMS-specific. In this case, the APIs
fetching content are not aware (nor are they required to) that the
database they are connecting to is MySQL.</P>
<H2>Setup/Running</H2>
<P>Assuming you already have the necessary python packages installed,
go to the petclinic folder where the setup.py script is located.</P>
<P><FONT FACE="Courier New, monospace">bash$ <B>python setup.py</B></FONT></P>
<P>You will be prompted for the MySQL “root” password (not your
system's root password). This is so it can create the “petclinic”
database, and create a springpython/springpython account in order to
connect to it. It also builds a configuration file for CherryPy in
order to serve static content, including this page.</P>
<P>Finally, run the application.</P>
<P><FONT FACE="Courier New, monospace">bash$ <B>cd cherrypy</B></FONT></P>
<P><FONT FACE="Courier New, monospace">bash$ <B>python petclinic.py</B></FONT></P>
<P>Now you should be able to navigate a browser to
<A HREF="http://localhost:8001/">http://localhost:8001</A> and see
the web application.<BR><BR><BR>
</P>
</BODY>
</HTML>
